System Booster

home *** CD-ROM | disk | FTP | other *** search

/ System Booster / System Booster.iso / Commodities / WindowToFront / DocsEnglish / WindowToFront.doc < prev next >

Wrap

Text File | 1996-09-27 | 22.6 KB | 483 lines

WINDOWTOFRONT 1.1 WARNING: WindowToFront requires AmigaOS Release 2 (or higher). WindowToFront is an utility program that makes full use of Workbench's "Commodities Exchange" system. It allows to bring to front any non-backdrop window with the chosen number of mouse clicks on it and to send it to the background in several ways; it is also possible to choose a different number of clicks for three distinct types of window, and even one for the window border. All that can be done in various modes that are selectable with a control panel or using the tool types. WindowToFront can be started from both Shell and Workbench, it can save into its icon the preferred settings and it can be adapted to any language using the locale.library or with a text file. Before continuing, I wish to apologize for my very poor english: I'm italian and in the high school I studied german. 1. THE HISTORY I wrote WindowToFront to remedy a problem of the similar ClickToFront program that comes with the 2.x operating system. That program allows to bring to front any window with a double-click of the mouse: it isn't possible, with it, to choose a different number of clicks. This wouldn't be by itself a serious problem to most users, were it not for a fact: by double-clicking on a disk icon in the main Workbench window (if it isn't backdrop) not only the disk's window opens, but the Workbench window also pops to the front, thus covering everything else on the screen, except the window just opened. At first I attempted to write a program able to recognize a double click on an icon as opposed to a double click on a free zone of the window, but this came out to be impossible: it doesn't exists any (documented) info in the system structures about the position of the Workbench icons. Specifically I discovered that they aren't gadgets, as a reading of the include file "workbench/workbench.h" may induce to believe. So the only way to make sure a double click on an icon doesn't bring the Workbench window to the front is to impose MORE than two clicks to bring it to front. Obviously this is necessary only for the Workbench window, so for the others it's enough to make the usual two clicks; besides someone could even not be annoyed at all as I am because of the above problem. So I wrote WindowToFront trying to meet everyone's needs: with it you can choose a number of clicks between 1 and 4 to bring to front three different types of window, and (that which ClickToFront doesn't allow) you can even send a window to back, always with an appropriate number of mouse clicks, usually combined with a qualifier such as ALT or CTRL. 2. GENERAL NOTES WindowToFront does nothing when the user select a gadget within a window. Some programs handle privately a double click on their gadgets, so WindowToFront should not interfere with them. Furthermore, WindowToFront doesn't bring to front the backdrop windows. This may seem obvious, but there are public domain programs, such as, for instance, DMouse, that do just that! Did you ever attempt to use the Hex program (file editor by Nicola Salmoria) while DMouse runs in background and allows to bring to front the windows? Did you notice that, after a while, the Hex's calculator mysteriously disappears? It doesn't really disappear, but is concealed by the main (backdrop) window of Hex, onto which, it would seem, many mouse clicks are made within a short time. 3. SHELL USAGE To know the Shell template of WindowToFront, you can simply enter the typical WindowToFront ? The template, however, is the following: CX_PRIORITY/N/K,CX_POPKEY/K,CX_POPUP/K,CLICKS/N/K,CLICKS_WB/N/K,CLICKS_ WBWIN/N/K,CLICKS_BORDER/N/K,CLICKS_BACK/N/K,QUALIFIER/K,QUALIFIER_BACK/K,WB ONLY/K,AUTOBACK/K,ACTIVATEBACK/K,TEXTFILE/K,GADGETS/K: The keywords appearing here match exactly the tool types you can insert in the WindowToFront's icon. Let's see their meaning and default values: CX_PRIORITY=<num> [default: 0] CX_POPKEY=<hotkey> [default: CTRL w] CX_POPUP=<YES | NO> [default: NO] These three are common to all Commodities programs. They allow to specify the priority of the WindowToFront task compared to the others (the default is suggested), the key sequence that makes the control panel appear if it is hidden, and whether the panel must pop up at the program's start or remain hidden until called via the hotkey. CLICKS=<number of clicks> [default: 2] This allows to choose the number of clicks that will be needed to bring to front a "normal" window, i. e. one that is neither the Workbench main one nor that of a Workbench disk or drawer (in short one that can't contain icons). The selectable number of clicks varies from 1 to 4. Anyway, a single click is strongly inadvisable, as it creates a lot of confusion. Specifying 0 as number of clicks disables this function. CLICKS_WB=<number of clicks> [default: 3] This allows to choose the number of clicks to bring to front the main window of the Workbench, that is the one in which the disk icons appear. This is possible only if the window wasn't made backdrop. The suggested number for this option is 3, so that a double click on an icon doesn't bring to front the whole window. Specifying 0 as number of clicks disables this function. CLICKS_WBWIN=<number of clicks> [default: 2] With this you specify the number of clicks for the Workbench windows associated to a disk or to a drawer. Because these windows are usually smaller than the entire screen, normally it doesn't matter very much if they get brought to front "accidentally" by opening an icon that is located within them, therefore you can easily specify 2 for this option: naturally the final choice goes to the user. Specifying 0 as number of clicks disables this function. CLICKS_BORDER=<number of clicks> [default: 2] This allows to specify the number of click to bring to front any window when the mouse pointer is on its border or on its title bar (excluding the system gadgets). Even the Workbench window can be brought to front with only two clicks this way (because on the title bar certainly can't be found any icon), while you can continue to use three of them for the inside of the window. Specifying 0 as number of clicks DOES NOT disables the function, but means that the number of clicks to use for the border is the same defined for the inside of the window (differentiating between the three types of window). Otherwise the number of clicks for the border is the same for all window types. CLICKS_BACK=<number of clicks> [default: 1] With this you specify the number of clicks that will be needed to send to the background any window when you will simultaneously press the key (or keys) indicated by the QUALIFIER_BACK (see below). Because for this operation it is needed (usually) a qualifier, there are no problems to specify 1 as number of clicks: in fact, it is the more convenient choice. Specifying 0 as number of clicks disables this function. QUALIFIER=<qualifier> [default: NONE] The qualifier is that key or combination of keys (as, for instance, CTRL ALT) that must be held pressed while clicking on windows to make the bring-to-front function actually work. Because in most cases the need to press one or more keys together with the mouse button slows down the operations (of the user, not of the computer), it is advisable to specify NONE for this option. QUALIFIER_BACK=<qualifier> [default: LALT] This qualifier, instead, is indispensable to be able to distinguish between clicks made to bring a window to front and clicks made to send it to the background. If the qualifiers for both operations were NONE or if they were equal, the send-to-back operation would always override the other (it would be the only one to be executed). This may seem odd, but in fact it is intentional, to discourage such a senseless and confusing choice. The default background qualifier is the left ALT key, and it can be changed with this tool type. I advise against the use of the SHIFT keys, already handled by the Workbench, and of the AMIGA keys, that have a special significance to Intuition. This means that the keys more suitable to carry out this task are the two ALTs and CTRL. A note on the qualifiers: by specifying separately two analogous keys, such as "LALT RALT", it will be required to SIMULTANEOUSLY press these keys. By specifying instead only their common part, such as "ALT", it will suffice to press any one of the two to perform the associated operation. See also the paragraph 6 for a complete listing of the names suitable as qualifiers. WBONLY=<YES | NO> [default: YES] By default, WindowToFront performs its function only with the windows that appear on the Workbench screen (or on the default PUBLIC screen). By specifying NO here you obtain that the program work on the windows of all screens. Sometimes this may cause contrast with the operations of the program that opened these screens but usually there are no particular problems. Note: for this tool type and all others of the same type (YES/NO) any specification different from "NO" (even a null string, such as "AUTOBACK=" or "WBONLY") will be interpreted as YES. AUTOBACK=<YES | NO> [default: NO] The specification of YES here means that by using the number of clicks chosen to bring a window to front on a window that is already in front of all others (that is, it isn't obscured by others) this window will be sent to the background. If the window is instead partially obscured it will be brought to front as usual. ACTIVATEBACK=<YES | NO> [default: NO] Usually a window you send to the background is a window you don't want to use for the moment, so there's no point at all in activating it. In fact by default WindowToFront won't activate the window you send to back in the normal way (that is, with the combination QUALIFIER_BACK + CLICKS_BACK), even if it will do so in the case of windows "sent away" with the AUTOBACK method. By specifying YES here you will make WindowToFront always activate the windows it sends to the background (although the reason of such a choice is completely beyond me). TEXTFILE=<filename> [default: S:wtf.txt] This keyword's purpose is to specify the name of the text file containing the strings the program will have to use while it is running. This allows to localize the program (to adapt it to a particular language) even if you don't own the locale.library. The text file must be written in a specific format. See the paragraph 7, "Localization", to have more detailed information about this topic. GADGETS=<YES | NO> [default: NO] Lastly, with this option you can tell the program whether you want the WindowToFront's control panel have at its bottom the two gadgets "Hide" and "Quit". They aren't needed, as these two options are already present in the "Project" menu and their elimination allows to save some space by having a shorter window, but their presence could be a commodity some people just can't do without. 4. WORKBENCH USAGE The usage from Workbench is analogous to that of all others Commodities: you have just to run the program by double-clicking on its icon. This operation will bring up the control panel if among the icon's tool types there is "CX_POPUP=YES", otherwise the program will start to run "silently" in the background. To make the control panel appear you will then need to press the key combination specified with the "CX_POPKEY" tool type (also in the icon). With the "Information..." item of the Workbench's "Icons" menu you can add, delete and modify the tool types of the WindowToFront's icon. Alternatively, after you have modified the working parameters of WindowToFront using the control panel, you can save these parameters into the program's icon with the "Save" item of the "Project" menu. However some parameters, as for instance "CX_POPUP", can't be modified this second way. The tool types recognized by WindowToFront from Workbench and their possible values are exactly the same described in the previous paragraph. By moving WindowToFront into the "WBStartup" drawer (with its icon) the program will be launched automatically at every reboot. In this case you need to insert "DONOTWAIT" among the icon's tool types, as WindowToFront, as the other Commodities, isn't reentrant. 5. THE CONTROL PANEL It would not be really necessary to describe the usage of the control panel, because it's very intuitive, however let's examine briefly the various gadgets and menu. In referring to them I'll use their english name. "Hot Key:" - It allows to modify the hotkey (key combination) that is needed to bring up the control panel. If you insert there an incorrect expression the gadget's previous contents will be restored (after you press RETURN). Warning: capital letters such as "W" imply a simultaneous SHIFT key press. "About..." - It causes the appearance of a requester with some info on the program and the author. It is not a Copyright message as the program is public domain. "Normal Windows:" - This slider allows to change the number of clicks to use to bring in front the "normal" windows (those not belonging to the Workbench and not being able to contain icons). The change takes place in real time, that is, you don't need to close the control panel to make it operating. "Main Workbench Window:" - As above, but for the main Workbench window, that which contains the disk and Ram/Rad disk icons. "Workbench Windows:" - As above, but for the others windows owned by the Workbench (for example drawers). "Window Border:" - As above, but for the border of any window. Setting this slider as "Off" you obtain that the number of clicks to use on the border be the same you use inside the windows. "To Back:" - With this slider you specify the number of clicks to use to send the windows to the background (when it is simultaneously pressed the qualifier associated to this operation). "Workbench Only:" - This checkbox allows you to choose whether WindowToFront must operate on the windows of all screens or only on those of the Workbench screen. "AutoBack:" - Checkbox to activate/deactivate the AUTOBACK facility (see paragraph 3). "Activate Back:" - Checkbox to specify whether the windows sent to the background must be activated or not. This gadget will be disabled if the number of clicks to send windows to back is 0 (Off) or if it's 1 and you didn't specify any qualifier for the "send to back" operation. In the latter case it's in fact necessary to always activate the window on which you click, or else no window will ever be able to be activated (at least in the usual mode, with a single click without qualifiers). "To Front:" - This string gadget contains the qualifier for the "Bring the window to front" operation. By inserting (with RETURN) an invalid qualifier the previous value will be restored. By inserting a null string it will be displayed NONE or the equivalent term of the used language. It is possible to use directly that term or NONE (always valid with any language) to specify that indeed it isn't required any qualifier for the mentioned operation. "To Back:" - Exactly as above, but for the "Send the window to back" operation. It is strongly inadvisable to insert NONE here. "Hide" - This gadget is present only if you specified the tool type GADGETS=YES at the launch of WindowToFront (on the command line or in the icon). Its function is to make the control panel disappear keeping WindowToFront active in the background. You can achieve the same effect by pressing the "H" key (or another key depending on the used language, as specified in the configuration file or in the catalog file). To recall the control panel you must press the hotkey. "Quit" - This gadget is present only if you specified the tool type GADGETS=YES at the launch of WindowToFront (on the command line or in the icon). Its function is to terminate the execution of WindowToFront and to remove it from memory. You can achieve the same effect by pressing the "Q" key (or another key depending on the used language, as specified in the configuration file or in the catalog file). "Save" (Project menu) - By selecting this menu item you save the current settings (hotkey, number of clicks, options, qualifiers) into the icon of WindowToFront. If that doesn't exist, the program creates it first. "Hide" (Project menu) - This menu item has the same function as the homonymous gadget (see). "Quit" (Project menu) - This menu item has the same function as the homonymous gadget (see). Lastly, it's worth remembering that the close gadget of the window of WindowToFront has the same effect as the "Hide" menu item (or gadget). 6. QUALIFIERS RECOGNIZED BY THE COMMODITIES.LIBRARY This is a listing of the qualifiers recognized by version 37 of the commodities.library and usable with WindowToFront. QUALIFIER MEANING LCOMMAND Left AMIGA key RCOMMAND Right AMIGA key LSHIFT Left SHIFT key RSHIFT Right SHIFT key LALT Left ALT key RALT Right ALT key CAPSLOCK Caps Lock key CONTROL CTRL key SHIFT Any SHIFT key CAPS Any SHIFT key or Caps Lock ALT Any ALT key Note: starting with version 38 (OS 2.1) of the commodities.library there are several synonyms for these qualifiers, but it's not necessary to list them here. If you own the 2.1 or 3.0 operating system you should find them reported in the system software manual. 7. LOCALIZATION By default WindowToFront communicates with the user in the english language, but, as I already said, the program can be localized, i. e. adapted to a specific language. If you are among the lucky ones owning the 2.1 or 3.x operating system, you can (and should) take full advantage of the localization capability of WindowToFront in the Amiga's soon-to-be-standard way, namely by using the locale.library. All you have to do is to copy the "windowtofront.catalog" file for your language, if supplied, to the directory LOCALE:Catalogs/<langname>, where <langname> is the name of your locale language. For example, if you are italian, you could copy the file "Catalogs/italiano/windowtofront.catalog" (found in the WindowToFront's distribuction directory) to the directory "LOCALE:Catalogs/italiano/" of your system, thus obtaining the localization file "LOCALE:Catalogs/italiano/windowtofront.catalog". Of course you must also, if you don't have already done that, set your preferred language with the Locale preferences editor. If you, on the other hand, don't have the locale.library or don't find the .catalog file you need, you still can localize WindowToFront by using an alternate method. This method consist of using the TEXTFILE keyword or tool type to let WindowToFront know the name of an ASCII text file containing the program's strings in the desired language, for instance by invoking the program with WindowToFront TEXTFILE=WORK:Config/wintofront.txt [other arguments here] if the text file's name is "wintofront.txt" and it is in the "WORK:Config" directory. If you don't use the TEXTFILE parameter WindowToFront will search a text file with the default name, that is "S:wtf.txt"; if no file is found the program will use its default internal strings, that are in english language (unless, of course, you can use the standard localization method). Anyway, the size of the control panel and the position of the gadgets will be adapted to the length of the used strings. I'll not explain the format of the text file (rather intuitive), as you shouldn't create one by yourself, but rather use (translating it into your language if necessary) one of those included with WindowToFront (tipically the english one, supplied just for that). The lines of the file to translate or modify are the ones NOT beginning with a number. The others must be leaved as they are, and can be used as a reminder of the contents of the original string. With version 1.1 of WindowToFront I supplied officially the files for the english and italian language; in the future I'll manage to add others of them. NOTE 1: If you put together versions for other languages of the .catalog or text file, you're free (and welcome) to include them in the WindowToFront's directory before you redistribute the program, or even to spread them separately, always of course in the public domain. NOTE 2: The format of the localization text file is changed from that recognized by WindowToFront 1.0, so you MUST use or modify one of those supplied with this version of the program; this means you CAN'T reuse the one you used previously with the mentioned version 1.0. NOTE 3: The text file expedient, if it is used, overrides the "normal" localization method, even if the locale.library is present. To avoid this, if you plan to use only the standard localization method, you must make sure that there is no "wtf.txt" file in your system's S: directory (and obviously do not use the TEXTFILE keyword or tool type). 8. WARNINGS Generally to specify only one click without any qualifier for any operation causes confusion and serious troubles in the user's handling of the windows as well as interaction problems between him and Intuition. It is recommended, therefore, to NOT do that. Furthermore it is worth pointing out that starting with version 1.1 WindowToFront is able to save its settings even if in its directory there is not an icon named after it; in this case the program will create a new icon for itself. Finally, for various reasons it would take too much time to explain, I suggest you to not rename the program. Anyway "WindowToFront" is its official name and so I intend it to be known by Amiga users worldwide. 9. EXISTING REVISIONS 1.1 The localization now also supports the locale.library (and in the future it will support only that). The look of the panel is slightly better. Now WindowToFront is able to create its icon if this doesn't exist while saving the settings. Also added some error messages. The about requester is now an EasyRequester. Lastly, the executable is now 612 bytes shorter. 1.0 The original version. 10. FINAL NOTES If you discover bugs, have doubts or want to send me suggestions (always welcomed) for the future versions of WindowToFront write to: Massimo Tantignone Via Campagnoli, 4 28100 NOVARA ITALY And now for a traditional conclusion: // Thanks to \X/ AMIGA for being the best computer ever!